home *** CD-ROM | disk | FTP | other *** search
/ Chip: Internet / Chip Internet.iso / viewer / wecj20 / ecjapi.txt < prev    next >
Text File  |  1995-01-10  |  12KB  |  334 lines
  1. Express Compression JPEG Application Program Interface (ECJAPI)
  2.  
  3. (c) 1993,1994 Expressed Compression Laboratories
  4. ********************************************************************************
  5.  
  6. ECJ_Decode (2.x)
  7. --------------------------------------------------------------------------------
  8. #include "ecjapi.h"
  9.  
  10. HANDLE ECJ_Decode( lpstrfilename, wParam, lParam, lpfnECJ_CallBack )
  11.  
  12. LPSTR    lpstrFileName;        /* name of file to decode */
  13. WORD    wParam;            /* attributes */
  14. LONG    lParam;            /* optional parameters */
  15. ECJCB    lpfnECJ_CallBack;    /* call back routine */
  16.  
  17. ECJ_Decode decodes the specified JPEG file and returns a device independent
  18. bitmap (DIB).
  19.  
  20. Parameter     Description
  21. ---------------------------------------------------------------------------
  22. lpstrFileName     Points to a null-terminated string that names the JPEG
  23.          file to be decoded.
  24.  
  25. wParam         Specifies how decoding shall proceed. This parameter
  26.          can be a combination of the following values.
  27.  
  28.          Value        Meaning
  29.          -------------- -------------------------------------------
  30.          ECJ_GRAY_ONLY    Create a gray only DIB.
  31.          ECJ_24_BITS    Create a 24 bit DIB.
  32.          ECJ_2_PASS    Use two-pass 24 to 8 bit colour quantisation.
  33.          ECJ_DITHER    Use FS dithering in 2-pass color quantisation.
  34.          ECJ_HALF_SIZE    Shrink the dimensions of the picture by half.
  35.          ECJ_4_SIZE    Shrink the dimensions of the picture by 1/4th.
  36.          ECJ_8_SIZE    Shrink the dimensions of the picture by 1/8th.
  37.          ECJ_AUTO_SIZE    Automatically shrink the dimensions of the
  38.                 picture when appropriate.
  39.  
  40.          ECJ_DITHER can only be used in conjunction with ECJ_2_PASS.
  41.          ECJ_GRAY_ONLY, ECJ_24_BITS and ECJ_2_PASS are mutually
  42.          exclusive. ECJ_HALF_SIZE, ECJ_4_SIZE and ECJ_8_SIZE are
  43.          mutually exclusive, while ECJ_AUTO_SIZE takes precedence over
  44.          all of them.
  45.          By default (with wParam = 0) ECJ_Decode creates an 8 bit DIB,
  46.          using single pass colour quantisation with ordered dithering
  47.          when appropriate.
  48.  
  49. lParam         Bits 24 to 30 can be used as an optional 7 bit label, which
  50.          is passed back to the client during callback, for the purpose
  51.          of uniquely identifying each call to ECJ_Decode when multiple
  52.          calls are made in parallel.
  53.  
  54. lpfnECJ_CallBack Specifies the procedure-instance address of the callback
  55.          procedure. ECJ_Decode sends messages and periodically passes
  56.          control back to the client via the ECJ callback procedure.
  57.          Setting this parameter to NULL disables the callback
  58.          mechanism.
  59.          For more information see the description of the ECJ_CallBack
  60.          function.
  61.  
  62. Returns
  63. =======
  64. The return value is the handle to the DIB if the function is successful.
  65. Otherwise, it is NULL.
  66.  
  67. See Also
  68. ========
  69. ECJ_CallBack
  70.  
  71. ********************************************************************************
  72.  
  73. ECJ_DecodeMem (2.x)
  74. --------------------------------------------------------------------------------
  75. #include "ecjapi.h"
  76.  
  77. HANDLE ECJ_DecodeMem( hStream, dwStreamLen, wParam, lParam, lpfnECJ_CallBack )
  78.  
  79. HGLOBAL    hStream;        /* handle to bitstream in memory */
  80. DWORD    dwStreamLen;        /* size of bitstream in bytes */
  81. WORD    wParam;            /* attributes */
  82. LONG    lParam;            /* optional parameters */
  83. ECJCB    lpfnECJ_CallBack;    /* call back routine */
  84.  
  85. ECJ_DecodeMem decodes the specified JPEG file and returns a device independent
  86. bitmap (DIB). ECJ_DecodeMem is essentially the same as ECJ_Decode, except
  87. that instead of taking a filename it takes a memory object as input.
  88.  
  89. Parameter     Description
  90. ---------------------------------------------------------------------------
  91. hStream         Global handle to memory object containing bitstream
  92.          to be decoded.
  93.  
  94. dwStreamLen     Size of the bitstream in bytes.
  95.  
  96. See ECJ_Decode for explanations on the rest of the parameters.
  97.  
  98. ********************************************************************************
  99.  
  100. ECJ_Crop (2.x)
  101. --------------------------------------------------------------------------------
  102. #include "ecjapi.h"
  103.  
  104. HANDLE ECJ_Crop ( lpstrInFileName, hInStream, lParam, dwInStreamLen,
  105.           lprectCropRect, lpstrOutFileName, lpdwOutStreamLen,
  106.           lpfnECJ_CallBack )
  107.  
  108. LPSTR    lpstrInFileName;    /* name of the source file */
  109. HANDLE    hInStream;        /* handle to input bitstream in memory */
  110. DWORD    dwInStreamLen;        /* size of input bitstream in bytes */
  111. LONG    lParam;            /* optional parameter */
  112. LPRECT    lprectCropRect;        /* cropping rectangle */
  113. LPSTR    lpstrOutFileName;    /* name of output file */
  114. LPDWORD lpdwOutStreamLen;    /* length of output bitstream */
  115. ECJCB    lpfnECJ_CallBack;    /* call back routine */
  116.  
  117. ECJ_Crop creats a windowed version of the input JPEG image, in accordance
  118. with the specfied cropping rectangle. This is achieved by direct manipulation
  119. of the input bitstream in the DCT domain, and no additional distortion is
  120. introduced in the process. The input bitstream is contained either in a source
  121. file or in a memory object. The output bitstream can be written directly to
  122. a specified file, or can be returned as a memory object.
  123.  
  124. Parameter     Description
  125. ---------------------------------------------------------------------------
  126. lpstrInFileName     Points to a null-terminated string that names the source
  127.          JPEG file. It should be NULL if the input is contained in
  128.          a memory object.
  129.  
  130. hInStream     Global handle to memory object containing the source JPEG
  131.          bitstream. It should be NULL if the input is contained in a
  132.          file.
  133.  
  134. lParam         Bits 24 to 30 can be used as an optional 7 bit label, which
  135.          is passed back to the client during callback, for the purpose
  136.          of uniquely identifying each call to ECJ_Decode when multiple
  137.          calls are made in parallel.
  138.  
  139. dwInStreamLen     Indicates the size of the bitstream in bytes if the input
  140.          is to be taken from memory.
  141.  
  142. lprectCropRect     The cropping rectangle. lprectCropRect.left specifies the
  143.          number of columns, in units of 8, that should be removed
  144.          from the left of the picture. lprectCropRect.right specifies
  145.          the number of columns, in units of 8, that should be removed
  146.          from the right edge of the picture. lprectCropRect.top and
  147.          lprectCropRect.right have similar semantics.
  148.          For 411 format images, all members should have even values.
  149.          The minimum cropping unit is this case is 16x16.
  150.          For 422 format images, the left and right members should
  151.          have even values, in which case the minimum cropping unit
  152.          is 16x8. A value supplied as odd which should have been
  153.          even will be truncated, with 1 subtracted from it.
  154.         
  155. lpstrOutFileName Points to a null-terminated string that names the output
  156.          JPEG file. It should be NULL if the output is to be
  157.          returned as a memory object.
  158.  
  159. lpdwOutStreamLen Returns the size of the output bitstream in bytes if the
  160.          output is to be returned as a memory object.
  161.  
  162. lpfnECJ_CallBack Specifies the procedure-instance address of the callback
  163.          procedure. See ECJ_Decode and ECJ_CallBack.
  164.  
  165. Returns
  166. =======
  167. If lpstrOutFileName is NULL, a handle to the memory object containing
  168. the output JPEG bitstream is returned upon successful completion.
  169. If the output is to be written to a file, an arbitrary, non-NULL value is
  170. returned. In both cases NULL is returned if the operation fails.
  171.  
  172. See Also
  173. ========
  174. ECJ_Decode, ECJ_CallBack
  175.  
  176. ********************************************************************************
  177.  
  178. ECJ_CallBack (2.x)
  179. --------------------------------------------------------------------------------
  180. #include "ecjapi.h"
  181.  
  182. int CALLBACK ECJ_CallBack( mMsg, wParam, lParam )
  183.  
  184. WORD    mMsg;    /* message */
  185. WORD    wParam;    /* first message parameter */
  186. LONG    lParam;    /* second message parameter */
  187.  
  188. The ECJ_CallBack function is an application-defined callback function that
  189. processes messages sent by ECJ_Decode.
  190.  
  191. Parameter    Description
  192. --------------------------------------------------------------------------
  193. mMsg        Specifies the message.
  194.  
  195.         Message        Meaning
  196.         -----------------------------------------------------------
  197.         ECJ_RESOLUTION    Upon decoding the header of the image
  198.                 ECJ_Decode returns with the following
  199.                 information:
  200.  
  201.                 Parameter   Bits   Meaning
  202.                 -------------------------------------------
  203.                 lParam        0-15   Vertical dimension.
  204.                 lParam       15-32   Horizontal dimension.
  205.                 wParam        0-2    Video format.
  206.                            0 = Y;
  207.                            1 = YUV422;
  208.                            2 = YUV411;
  209.                            3 = YUV444;
  210.                 wParam         3     Picture shrunk by half.
  211.                 wParam         4     Picture shrunk by 1/4th.
  212.                 wParam         5     Picture shrunk by 1/8th.
  213.  
  214.         ECJ_PROGRESS    ECJ_Decode periodically returns control to
  215.                 the client with progress information:
  216.  
  217.                 wParam    Stage
  218.                 ------  ----------------------------------
  219.                 0    Pass 1
  220.                 1    Creating histogram
  221.                 2    Pass 2
  222.  
  223.                 For stages 0 and 2, lParam indicates percentage
  224.                 completion.
  225.  
  226.         ECJ_ERROR    An error has occured. wParam identifies the
  227.                 particular error.
  228.  
  229.                 wParam    Error
  230.                 ---------------------------------------------
  231.                  1    File is not JPEG.
  232.                  2    Can't open file.
  233.                  3    Unexpected EOF.
  234.                  4    Out of memory.
  235.                  5    Unrecognised video format.
  236.                  6    Unexpected scan component.
  237.                  7    Unexpected marker.
  238.                  8    Unexpected RST.
  239.                  9    Unsupported precision.
  240.                 10    User abort.
  241.  
  242. wParam        Bits 8-14 contains the optional 7 bit label passed to the DLL.
  243.         The remaining bits contain message-dependent information.
  244.  
  245. lParam        More message-dependent information.
  246.  
  247. Returns
  248. =======
  249. To continue decoding a value of 0 shall be returned.
  250. A return value of -1 instructs ECJ_Decode to abort decoding immediately.
  251.  
  252. Comments
  253. ========
  254. The client does not have to process any of the messages. The simplest
  255. ECJ_CallBack function can simply return 0. A more well behaved application
  256. should take the opportunity to momentarily pass control back to Windows
  257. to achieve non-preemptive multitasking.
  258.  
  259. See Also
  260. ========
  261. ECJ_Decode
  262.  
  263. ********************************************************************************
  264.  
  265. ECJ_Info (2.x)
  266. --------------------------------------------------------------------------------
  267. #include "ecjapi.h"
  268.  
  269. int ECJ_Info( lpstrfilename, lpX, lpY, lpColourFormat )
  270.  
  271. LPSTR    lpstrFileName;        /* name of JPEG file */
  272. LPINT    lpX;            /* horizontal size */
  273. LPINT    lpY;            /* vertical size */
  274. LPINT    lpVideoFormat;        /* video format */
  275.  
  276. ECJ_Info provides some basic information on the specified JPEG file, which
  277. would otherwise be unavailable when the CallBack mechanism is not used. In
  278. particular the video format information is useful in determining the minimum
  279. cropping units.
  280.  
  281. Parameter     Description
  282. ---------------------------------------------------------------------------
  283. lpstrFileName     Points to a null-terminated string that names the JPEG file.
  284.  
  285. lpX         Pointer to integer which contains the horizontal size of
  286.          the picture upon successful return.
  287.  
  288. lpY         Pointer to integer which contains the vertical size of
  289.          the picture upon successful return.
  290.  
  291. lpVideoFormat     Pointer to integer which contains the chroma-subsampling
  292.          format of the picture.
  293.          0 = Y; 1 = YUV422; 2 = YUV411; 3 = YUV444;
  294. Returns
  295. =======
  296. Returns 0 if the function is successful.
  297.  
  298. See Also
  299. ========
  300. ECJ_InfoMem, ECJ_CallBack, ECJ_Crop
  301.  
  302. ********************************************************************************
  303.  
  304. ECJ_InfoMem (2.x)
  305. --------------------------------------------------------------------------------
  306. int ECJ_Info( hStream, dwStreamLen, lpX, lpY, lpColourFormat )
  307.  
  308. HGLOBAL    hStream;        /* handle to bitstream in memory */
  309. DWORD    dwStreamLen;        /* size of bitstream in bytes */
  310. LPINT    lpX;            /* horizontal size */
  311. LPINT    lpY;            /* vertical size */
  312. LPINT    lpVideoFormat;        /* video format */
  313.  
  314. ECJ_InfoMem provides some basic information on the specified JPEG bitstream.
  315. ECJ_InfoMem is essentially the same as ECJ_Info, except that instead of
  316. taking a filename it takes a memory object as input.
  317.  
  318. Parameter     Description
  319. ---------------------------------------------------------------------------
  320. hStream         Global handle to memory object containing bitstream.
  321.  
  322. dwStreamLen     Size of the bitstream in bytes.
  323.  
  324. See ECJ_Info for explanations on the rest of the parameters.
  325.  
  326. Returns
  327. =======
  328. Returns 0 if the function is successful.
  329.  
  330. See Also
  331. ========
  332. ECJ_Info, ECJ_CallBack, ECJ_Crop
  333.  
  334.